<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
    <title>Calling BHF Components</title>
    <base href="http://bhs.googlecode.com/svn/trunk/"><!--[if IE]></base><![endif]-->
</head>
<body bgcolor="white">
<h1>Calling Blue Hole Framework (BHF) Component From JavaScript</h1>
<p>
    If you are calling BHF Component from other client side frameworks, you will need to understand Raw Invocation
    and, if going cross domain with script elements, the callback parameters. If you will be using the BHF client side
    support at the JavaScript level, you can simply create a Component and add the needed methods and events.
    If you do not mind using JSP, we also provide a component tag to do the Component creation for you.
</p>
<h2>Raw Invocation</h2>
<p>
    Calling BHF Components directly is a matter of <a href="javadoc/org/bhf/services/package-summary.html">
    URL, parameters, and response</a>. You are responsible for handling the response, including updating the
    Component state and dispatching any events.
</p>
<h2>The <code>success</code> Parameter</h2>
<p>
    When invoking Components across domains (cross server, cross origin, ...), one cannot use the XMLHttpRequest
    invocation method used bhs.js or prototype.js. Instead one must resort to one of several hacks to work around
    the XMLHttpRequest same origin security policy. One or the more popular techniques employs dynamic script
    elements. To support this usage pattern, BHF services may be invoked with an optional 'callback=' parameter to
    wrap the returned JSON object with a function call.
</p>
<h2>Using bhs.js</h2>
<p>
    To use the bhs.js library, you will be using a BHF.Component object to make invocation requests to Components. Note
    that a Component object uses XmlHTTPRequest and, therefore, can only be used within a domain (same origin).
    Each Component enforces a dispatch policy on the requests managed by that Component:
    <dl>
        <dt><code><b>BHF.Service.DISPATCH_POLICY.CONCURRENT</b></code></dt><dd>Allow concurrent requests.</dd>
        <dt><code><b>BHF.Service.DISPATCH_POLICY.SERIAL</b></code></dt><dd>Only allow one request at a time.</dd>
    </dl>
    All policies govern ONLY the invocation requests associated with a single Component.
</p>
<p>
    To create a Component and add methods and events: for example...
    <pre><code>
    MyApplication.calculator = new BHF.Component( 'service/calculator/{id}/{method}' );
    MyApplication.calculator.addMethod( 'compute' );
    MyApplication.calculator.addEvent( 'update' );
    </code></pre>
    and to make an invocation request...
    <pre><code>
    MyApplication.calculator.add(
        {
            success: function( o )
            {
                ...
            },
            failure: function( o )
            {
                ...
            },
            precondition: function()
            {
                ...
            },
            rollback: function()
            {
                ...
            }
        },
        5
    );
    </code></pre>
    <p>
        The callbacks and argument are the same as <a href="docs/calling-services.html">for Services</a>, except that
        Component introduces two additional pre-defined preconditions:
        <dl>
            <dt><code>BHF.Component.PRECONDITIONS.SAME_STATE</code></dt><dd>The state of the Component must be
                the same as when the method invocation was dispatched.</dd>
            <dt><code>BHF.Component.PRECONDITIONS.SAME_STATE_ARG</code></dt><dd>The state of the Component must be
                the same as when the method invocation was dispatched <em>and</em> the argument must be they
                same as well. (This option only make sense if you pass a function as the argument so that the
                argument value can be checked after invocation.)</dd>
        </dl>
    </p>
</p>
<h2>Inline Synchronous Invocations</h2>
<p>
    As <a href="docs/calling-services.html">with Services</a>, you can invoke Component methods synchronously inline.
</p>
<h2>Using JSP</h2>
<p>
    If you choose to use JSPs, you can declare a Component, equivalent to the code above, as follows. (Calling the
    Component is identical to the JavaScritp example.)
</p>
<pre><code>
    &lt;%@ taglib uri="http://bhf.org/taglibs/bhf" prefix="bhf" %&gt;
    ...
    var myComponent = &lt;bhf:component
        reference="MyApplication.calculator"
        serviceClass="example.CalculatorComponent"
        moduleClass="example.ServiceModule"
        absolute="true"
    /&gt;
</code></pre>
</body>
</html>